Previous Book Contents Book Index Next

Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /
Chapter 16 - Storage Objects

Using Storage Objects

As indicated earlier, you use storage objects to represent physical storage devices available on a computer. Most often, you'll simply create a new storage object associated with some part of a storage device (for instance, with some file on a disk drive) and then attach that storage object to a file object (by calling the Q3File_SetStorage function). If necessary, you can also get or set some of the information associated with a particular storage object. For example, you can determine the file reference number of the open file associated with a Macintosh storage object. This section describes how to perform these two tasks.

Creating a Storage Object

Creating a storage object essentially involves indicating to QuickDraw 3D the location and possibly also the size of the piece of physical storage you later want to read data from or write data to. Once you've created a storage object, you attach it to a file object and perform all I/O operations using file object functions. Listing 16-1 illustrates how to create a storage object connected to an open Macintosh file.

Listing 16-1 Creating a Macintosh storage object

myErr = FSpOpenDF(&myFSSpec, fsCurPerm, &myFRefNum);
if (!myErr) 
   myStorageObj = Q3MacintoshStorage_New(myFRefNum);
Listing 16-2 illustrates how to open a file and create a UNIX storage object connected to that open file.

Listing 16-2 Creating a UNIX storage object

myFile = fopen("..:teacup.eb", "r");
if (myFile)
   myStorageObj = Q3UnixStorage_New(myFile);
Listing 16-3 illustrates how to allocate a block of memory and create a storage object connected to that block.

Listing 16-3 Creating a memory storage object

#define kBufferSize              256

myBuffer = malloc(kBufferSize);
if (myBuffer)
   myStorageObj = Q3MemoryStorage_NewBuffer
                                 (myBuffer, 0, kBufferSize);
In the code shown in Listing 16-1 through Listing 16-3, your application specifically reserves the desired piece of the physical storage device, either by opening a file or by allocating memory. In these cases, your application must also make sure to close the file or deallocate the memory block after you've closed or disposed of the associated storage object.

Note, however, that QuickDraw 3D provides two types of memory storage functions. The function Q3MemoryStorage_NewBuffer creates a new memory storage object using a specified buffer. The function Q3MemoryStorage_New creates a new memory storage object but copies the data in the specified buffer into its own internal memory. If you create a storage object by calling Q3MemoryStorage_New, you can dispose of the buffer once Q3MemoryStorage_New returns.

IMPORTANT
Whenever you create a storage object associated with an open file or an allocated memory block, you must close the file or dispose of the memory yourself. Whenever QuickDraw 3D opens a file or allocates memory to create a storage object, it closes the file or disposes of the memory itself.
It's possible, however, to have QuickDraw 3D create and manage a piece of storage for you. For example, you can create a memory storage object by calling Q3MemoryStorage_NewBuffer as follows:

myStorageObj = Q3MemoryStorage_NewBuffer(NULL, 0, 0);
Notice that the first parameter in this call is NULL; this value indicates that you want QuickDraw 3D to allocate a buffer internally and automatically expand the buffer whenever necessary. (The initial size of the buffer and the grow size of the buffer are determined by internal QuickDraw 3D settings.) In addition, when you close or dispose of the storage object, QuickDraw 3D disposes of any memory it has allocated on your behalf.

You can also have QuickDraw 3D open and close files on your behalf. On the Macintosh Operating System, you can call the Q3FSSpecStorage_New function, passing a file system specification structure describing a closed file. The following line of code illustrates how to do this:

myStorageObj = Q3FSSpecStorage_New(&myFSSpec);
QuickDraw 3D opens the file and creates a storage object associated with that file. When you later close or dispose of that storage object, QuickDraw 3D also closes the associated Macintosh file. Similarly, you can call Q3UnixPathStorage_New to have QuickDraw 3D open a file described by a path name and create a new storage object associated with it. When you later close or dispose of that storage object, QuickDraw 3D also closes the associated file.

WARNING
No matter whether you opened a piece of storage (that is, a file or a block of memory) yourself or allowed QuickDraw 3D to open it for you, you must not access that piece of storage once you've created a storage object to represent it. QuickDraw 3D assumes that it has exclusive access to all data in any part of a physical storage device associated with an open storage object.

Getting and Setting Storage Object Information

QuickDraw 3D provides routines that you can use to get or set some of the information it maintains about storage objects. For example, you can get the file reference number of the Macintosh file associated with a Macintosh storage object by calling the function Q3MacintoshStorage_Get. Similarly, you can determine the starting address and size of a buffer associated with a memory storage object by calling Q3MemoryStorage_GetBuffer.

In general, the routines that get and set storage object information operate like the get and set routines for other types of QuickDraw 3D objects, but with several important differences:

Previous Book Contents Book Index Next

© Apple Computer, Inc.
11 JUL 1996